package compoundDB.database;

import compoundDB.core.*;

import java.sql.SQLException;
import java.util.List;

/**
 * This interface specifies the method calls the core will be able to make to
 * get compound information from a database query.
 * 
 * @author Kohl Bromwich
 * 
 */
public interface QueryReader
{
	/**
	 * This method closes the contained database ResultSet, and cleans up
	 * anything necessary internally.
	 * 
	 * @throws SQLException
	 *             if an error occurs comunicating with the database.
	 */
	void close() throws SQLException;
	
	/**
	 * Gets the next compound after the current position, and moves the position
	 * to the next compound.
	 * 
	 * @return The compound at the current position, or null if the position is
	 *         at the end of the results.
	 * 
	 * @throws SQLException
	 *             If an error occurs communicating with the database.
	 */
	Compound getCompound() throws SQLException;
	
	/**
	 * This method will return the number of compounds contained within this
	 * query reader.
	 * 
	 * @throws SQLException
	 *             if an error occurs comunicating with the database.
	 * 
	 * @return The number of compounds contained within the QueryReader.
	 */
	int getCompoundCount() throws SQLException;
	
	/**
	 * This method will return a specified number of compounds starting at the
	 * specified number (or less if it reaches the end of the compounds).
	 * 
	 * @param startCompound
	 *            The one-based (first row is 1) position in the results where
	 *            compounds should start being collected from.
	 * 
	 * @param numOfCompounds
	 *            The preferred (maximum) number of compounds to be returned.
	 * 
	 * @return The range of compounds specified from the search results.
	 * 
	 * @throws SQLException
	 *             if an error occurs comunicating with the database.
	 */
	List<Compound> getCompounds(int startCompound, int numOfCompounds)
			throws SQLException;
	
	/**
	 * This will seek to the compound in the result set, so that getCompound()
	 * will return the compound.
	 * 
	 * @param posCompound
	 *            The number compound in the results to seek to. Must be greater
	 *            than 0.
	 * 
	 * @throws SQLException
	 *             If an error occurs communicating with the database.
	 */
	void seek(int posCompound) throws SQLException;
}
